System Booster

home *** CD-ROM | disk | FTP | other *** search

/ System Booster / System Booster.iso / Textdisplayers / WANT / docs / WANT.doc next >

Wrap

Text File | 1996-09-27 | 21.6 KB | 583 lines

WANT Searches Documents for Keywords Requirements......Hardware & Software Installation......A New Concept Using WANT........Operating Instructions CLI Usage.........Command Line Template WB Usage..........Tooltypes Menus & Help Wildcards.........* Hot Tips..........For Advanced Users GNU Disclaimer....License About BOTH........Credits & Distribution By BOTH Software GiftWare © 1994 -------------------------------------------------------------------- SYSTEM REQUIREMENTS VERSION 1.017 -------------------------------------------------------------------- WANT needs: WB 2.x and up - Any Amiga AmigaGuide, or another text reader About 1 Meg of memory to hold a file. A Hard Drive would be nice, but not necessary. -------------------------------------------------------------------- How to install WANT -------------------------------------------------------------------- WANT is distributed in a single directory. Copy that directory and it's drawer icon to any place on your hard drive. The first time you run WANT, it will make all the necessary assigns to add itself to the system. (No more modifications to the startup-sequence!). The ASSIGNS are temporary. They will last only until you turn off the power or reboot. WANT makes these ASSIGNs to the system: WANT: DH?:WANT LIBS: WANT:libs ADD Caution: Do not make WANT resident. Do not move files out of WANT's directory. -------------------------------------------------------------------- Calling WANT from the CLI -------------------------------------------------------------------- TEMPLATE: WANT SOURCE,FILEREADER/K,EDITOR/KCOLOR/K,NOHIGHLIGHT/S,HIGHLIGHT/S, BOLD/S,ITALIC/S,UNDERLINE/S,REVERSE/S For a complete description of these command options, refer to the tooltypes section. Unlike the tooltypes, you do not have to enter the full path for EDITOR and FILEREADER as long as they are in the path. These commands are not positionally sensitive. If you simply enter WANT, the program will run with built-in defaults for the filereader, editor, highlighting and color. -------------------------------------------------------------------- OPERATING INSTRUCTIONS FOR WANT -------------------------------------------------------------------- What does WANT do for you? WANT will search a textfile, like INDEX, for instances of words you supply. For example, let's say you have the AmiNET INDEX file that lists all the files available from that mirror site. You want to know if a file called AGATE is in the list. WANT will search the file, looking for any instance of the word AGATE. Each line of the INDEX file that contains the word AGATE will be displayed on the screen. Let's try another example using INDEX - you want to find all the lines that contain the words DATATYPE and GIF. WANT will display any lines that have both words in it. WANT will also find lines with DATATYPE or GIF, thus narrowing your search. Use the cycle gadget labelled AND OR to select the function to use. The Execute button Want gives you many options to select from the operating panel. After you select all of the options necessary, click the Execute button. This button tells WANT to begin retrieving the information you asked for. Selecting a File with the File Requester You must select a file to search or view. If you forget, WANT will prompt you select a file from the file requester. The requester used in WANT was custom written for this application. It has some features you may not have seen before. To select a file or directory, just click the mouse once. Multiselection is not supported. The four buttons at the bottom are: PARENT, DRIVES, VOLUMES, and DIR. PARENT This button will select the directory above the one you are in. There is another, faster, way to invoke PARENT. Place the mouse pointer against the left edge of the screen and press the Left Mouse Button. DRIVES This will display all the physical devices attached to your Amiga. It will show hard drives, floppys, CD players, RAM, RAD, and others. VOLUMES This will display all ASSIGNS and VOLUMES seen by the system. DIR Since the Amiga is a multitasking beast, you might leave WANT to do something else and then come back. The contents of the requester may have changed in the meantime. By pressing DIR, the directory listing is updated. Viewing a Text File without searching for terms WANT will also display any selected file with the filereader of your choice. To read a selected file, select the "View a file" option then click Execute. You cannot search for terms when in this mode. Redirecting the output to a Text Editor Instead of a filereader, you may direct the output of WANT to the text editor of your choice. To do this, select the "Search and Edit" option. This option works like "Search and View", but no highlighting is permitted (or wanted). The default EDITOR is ED, but you can change that to your favorite with the tooltype. Be sure to include the full path to the editor. If you want to edit an entire file with the editor: Select a file Enter an asterick (*) as the ONLY search term Select "Search and Edit" Execute This will bring the entire file into your editor. Remember to SAVE AS when you save an edited file. The filename has been changed. The Asterick (*), as a single search term, is considered a wildcard, meaning all lines of the file will be 'found' and displayed. Also see wildcards Highlighting words found by a search The word or words you asked to see are, by default, bolded. This helps you locate the word more quickly. You can change the kind of highlighting with the checkboxes labelled BOLD, ITALIC, UNDERLINE, and REVERSE. You may use any or all of these options. Experiment with the buttons to see which type of highlighting you prefer. The checkmark box on the screen labelled HIGHLIGHT will allow you to disable the highlighting when checked. Clearing the text entry fields The button called CLEAR will erase the two text entry fields so you may enter new data. These fields can be erased individually by pressing Control X. Displaying extra lines on a search Not all files are as predictable as a mirror's INDEX. For example, the file you want to search may be an email letter or DOC file. By simply asking WANT to find a word and display the line that word was found in, you won't be able to see the word in it's proper context. Ideally, you would like to see a few lines before the word and a few lines after the word. The gadgets labelled LEADING LINES and TRAILING LINES let you select how many lines to display before and after the line with the word in it. Whole Word searches Normally, WANT will find a search term within another word. For example, if you ask for bet, WANT will find better. If you want to search for examples of whole words, just check the Whole Words box. Now your entty will be treated as if you typed a space before and after the word. Case Sensitivity Normally, WANT will treat your entries without regard to Case. If you need the case to be sensitive, check the Case Sense box. A pecularity of AmigaGuide If you use AmigaGuide as your filereader, you may find that searching an AmigaGuide document can give unpredictable results. If your search term is found in a line that begins with @NODE, AmigaGuide will get very confused. To see the results properly, try using the editor or a different filereader. For more detailed instructions on the operation of WANT and some ideas on how to use it to your advantage, see hot tips. -------------------------------------------------------------------- PULL DOWN MENUS -------------------------------------------------------------------- Pull-Down Menus PREFS HELP ABOUT QUIT Prefs is ghosted and not available in this version. Help will display this AmigaGuide file if your selected filereader is AmigaGuide. If you have selected another filereader, like More, the file called WANT.doc will be substituted. About will display information about BOTH Software. Quit will exit the program. -------------------------------------------------------------------- WILDCARDS -------------------------------------------------------------------- The Asterick (*), as a single search term, is considered a wildcard, meaning all lines of the file will be 'found' and displayed. The Asterick (*), when used as part of a search term means anything following is selected automatically. An example: gfx* will find any line with gfx and will highlight any characters following gfx. It would look like this: Videotracker2.lha gfx/misc 395K+Let graphics react to sound Another example: gfx*n will search for gfx and will highlight until it finds an "n". picmerge.lha gfx/conv 11K+Little utility for connecting 2 "*" will find anything enclosed in double quotes. "* will find the first quote mark in a line but highlighting will not occur. * and Whole Word will not work. The terms are too vague for GAWK to interpret. The Asterick follows the UNIX rules of the Period. Using an Asterick can result in unexpected highlighting results. We recommend you use caution for this reason. -------------------------------------------------------------------- RUNNING WANT FROM THE WORKBENCH -------------------------------------------------------------------- Customizing the look of WANT This section covers the tooltypes available for WANT. If you are not familiar with tooltypes, please refer to the operating instructions provided with your Amiga. WANT will accept five tooltypes: FILEREADER, EDITOR, HIGHLIGHT, COLOR, SOURCE If for any reason the tooltype you invoke does not seem to work, please examine your entry for spelling or syntax errors. WANT will not report these errors to you. To remove a tooltype, enclose it in parentheses, then SAVE. We all have our favorite filereaders. WANT won't limit you to using any one filereader. You may specify the reader of your choice in the icon's tooltype. The default filereader is AmigaGuide. If you prefer More or MultiView, or any other reader, just change the tooltype. The proper syntax is: FILEREADER=DH0:UTILITIES/MULTIVIEW The filereader MUST include the full path, like this: FILEREADER=DH2:TEXTREADERS/LOOKER Note: WANT expects to find More in SYS:UTILITIES. This is an internal default that you cannot change. This is done so that WANT has a standard default in case AmigaGuide is not present on your drive. If you are using V34 of the AmigaGuide.library, WANT will automatically turn off highlighting, since this version will not allow it. Several filereaders were tested for compatibility with WANT. Here are some that worked well with WANT: AmigaGuide Multiview More MuchMore PPMore CType Etale: (efr) will not show colors, but works well in all other respects. If you use this reader, set the color tooltype to: (COLOR=) View80: Will not display highlighting or colors. To use View80, enter the tooltype HIGHLIGHT=OFF. For more on Filereaders, see Hot Tips You may direct the output of WANT to a text editor. The tooltype is EDITOR. You MUST enter the full path of the text editor. EDITOR=SYS:C/ED Highlighting is set to OFF when using the editor. This way, the output file will not contain any of the Escape characters that WANT uses for highlighting. Highlighting options When WANT gets a 'hit' on a keyword, that word is highlighted in any combination of the following ways: Bold Underline Italic Reverse Bold is the default, but you may change to any other. You may actually select all of them, but before you do that, test the effect first by checking the boxes on the GUI. Whatever highlighting options you select in the tooltypes will be reflected as default values on the screen. To set the highlighting options in the icon, follow these examples: HIGHLIGHT=ITALIC HIGHLIGHT=REVERSE|BOLD HIGHLIGHT=BOLD|ITALIC|REVERSE Notice the vertical bar separating the options. This is the SHIFTED BACKSLASH key. By using the vertical bar, you may select more than one option. You may choose not to have Highlighting and Colors as a default. Select this by adding the word OFF to the HIGHLIGHTING tooltype. Example: HIGHLIGHT=OFF This option will disable all highlighting modes and colors. Colors The highlighted words can be made to print in one of the four basic colors of the WorkBench. You may have reset these color values from the original Gray, Black, White, and Blue. WANT can't tell what shades are actually being displayed. You will have to be the final arbitor of the colors. You may select, through the COLOR tooltype any one of these colors. Black is the default. If you have changed the palette preferences, Black may now be Mauve. You may have to experiment. Remember, select only one color: COLOR=WHITE (or BLACK, BLUE, GRAY) Default Directory Through the use of the SOURCE tooltype, you can select the path and filename that WANT will display in the listview. If you usually search files in the same directory, this is a timesaving feature. You can specify a directory or a directory and a filename. Here are some examples: SOURCE=AAMYFILES: SOURCE=AAMYFILES:INDEX Tooltype Summary FILEREADER=<path>filereadername EDITOR=<path>texteditor HIGHLIGHT=OFF BOLD ITALIC UNDERLINE COLOR=WHITE BLACK BLUE GRAY SOURCE=<path><filename> -------------------------------------------------------------------- Hot Tips -------------------------------------------------------------------- How to get the most from WANT You'll find that you usually search the same files. To search them quickly, make a directory called myfiles and put your favorite files in this directory. Then enter the following line in your startup-sequence: ASSIGN aamyfiles: <path>myfiles Notice the 'aa' preceeding the name. From WANT, click the VOLUMES button. The lists all the logical assigns made on your system, alpha- betically. The 'aa' will insure this ASSIGN is at the top of the list, making it easier for you to find it. What can you put in this directory? RECENTS and INDEXES for a start. Fred Fish listings, FAQs, articles, readmes, docs, and anything else you might want to look through. This method eats up some disk space, but saves you the hassle of hunting through directories to find files. When you search Fish listings, its a good idea to choose about 25 lines of leading and 5 lines of trailing context. You may adjust these numbers at any time. The more lines you select, the longer the search will take. (The filereader will take longer to load the file). Do you ever use FIND to locate a file on your hard drive? It's a great program, but by necessity, slow. You can create a file containing all the directories and files on your drive (or better yet, a partition) and then use WANT to search that file, rather than wait for FIND. Here's how to do it: Let's assume you have created the ASSIGN outlined above, and want to create a file that lists all the directories and files on your DH1: partition. From the CLI type this: list >aamyfiles:dh1contents DH1:* lformat "%F%N" ALL The drive light will come on for a while. When it turns off, the file called dh1contents will be in the directory myfiles. Now you can use WANT to search dh1contents. The search time should be less than one second on a 1200, and longer on a 7Mhz machine. This works on CDROMs and floppies also. Using an Editor instead of a filereader You can select an editor instead of a filereader in the Tooltypes. If your editor requires a stack to be set, WANT cannot do it for you. When the editor is called, it is passed the filename of a temporary file lovcated in RAM:. This file is named GAWK_OUTPUTxxxxxxxx. When you save your file, always SAVE AS with a different filename and path, or the results of your editing will be lost. A special note to the UN*X literate The two text entry fields will accept ANY UN*X-like search expressions. Multiple expressions separated by the AND/OR gadget are allowed. Any expression that could be used by egrep is allowed. i.e. [AaBb], all logical operators, and wildcards. Using UN*X Regular Expressions to search for more than two terms Enter the expression or multiple expressions like this: (word1)|(word2)|(word3) etc. This will find word1 OR word2 OR word3. If you click the AND OR gadget to AND, and enter another expression in the second text field, the the search will AND the two expressions. Since WANT is designed to shield UN*X from the user, you may encounted unpredictable results with multiple expressions. Grep and Gawk's scripts are being assembled algorithmically in realtime. This presents a large workload for the system. You CAN confuse the process with overly complex expressions. -------------------------------------------------------------------- GNU DISCLAIMER -------------------------------------------------------------------- EGREP & GAWK, the powers behind WANT EGREP & GAWK are powerful tools written by GNU. This is part of GNU's disclaimer. For the rest of it, read LICENSE. -------------------------------------------------------------------- This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. -------------------------------------------------------------------- ABOUT THE AUTHORS -------------------------------------------------------------------- WANT is GIFTWARE. That means if you like it and use it, you may send us a Gift. A birthday card or email would be nice. If you distribute the program, distribute the entire package. You may upload WANT to any BBS or archive. WANT may be freely distributed on club disks, by Amiga Reports and by Mr. Fred Fish. See below for a list of filenames to be included. WANT is free to use and copy as you see fit. The Authors retain all rights to the program. The Authors are not responsible for any damage the program may cause. WANT was tested on a 4000, 3000, 2000, 600, and a 1200 without problems. This is the first release of WANT. The next release will include a preferences section that allows you to preset groups of files to be searched. Predefined search terms and context lines for each group of files may be set. If you have any ideas about features WANT should include, please contact the authors. We wrote WANT so we could search INDEXES, RECENTS, and Fishlists, but we soon found other uses for it. We would really like to hear from you. If you find a character that causes problems with a search, please let us know. Files included in this release (1.00): WANT --------- The Executable egrep --------- The GNU file gawk ---------- The GNU file ixemu.library - Runtime Library for GNU utilities LICENSE ------- The GNU license WANT.guide ---- This AmigaGuide file WANT.doc ------ Instructions for the Guideless WANT.readme --- An unusually dull readme file Icons --------- If you find any bugs or have any comments, please contact the Authors: C & UN*X Code Program Design, GUIs, Docs -------------------------- -------------------------- Will Bow Colin Thompson 1531 Corinth Unit 1 9606 Carroll Cyn. Rd. H9 West Los Angeles, CA 90025 San Diego, CA 92126 (310) 478-4913 (619) 695-2181 InterNet: colin@cts.com A note to programmers: The file requester used in want will be available to you as a linkable object later this fall. We are still adding features to it. Look in dev/c for it. Credits WANT simply could not be written without including the code of many talented programmers who have bequeathed their work to the public domain. Their selfless acts of generosity allow us to continue the tradition of providing Free or Inexpensive Software to Amiga owners. Thanks to: Nico Francois for ReqTools Jan van deen Baard for GadToolsBox The GNU group for GCC 2.6.0 and all those great utilities Chad Randall for Iconian CDROM.COM for making the archives available Fred Fish for the same darn thing! Our many field testers including members of the San Diego Area Amiga Users Group for their invaluable ideas want.guide converted by Guide2Doc 1.0 (02-Nov-1993) FreeWare - © Koessi